Expand description
Rust bindings to the wasm-opt
WebAssembly optimizer.
wasm-opt
is a component of the Binaryen toolkit
that optimizes WebAssembly modules. It is written
in C++.
This project provides a Rust crate that builds wasm-opt
and:
- makes its command-line interface installable via
cargo install
, - provides an API to access it programmatically.
Installing the binary
cargo install wasm-opt --locked
It should behave exactly the same as wasm-opt
installed from other sources.
Using the library
The crate provides an OptimizationOptions
type that
follows the builder pattern, with options that closely
mirror the command line options of wasm-opt
. Once built,
call OptimizationOptions::run
to load, optimize, and write
the optimized module.
use wasm_opt::OptimizationOptions;
let infile = "hello_world.wasm";
let outfile = "hello_world_optimized.wasm";
OptimizationOptions::new_optimize_for_size()
.run(infile, outfile)?;
There are constructors for all the typical optimization profiles:
OptimizationOptions::new_optimize_for_size
·-Os
or-O
OptimizationOptions::new_optimize_for_size_aggressively
·-Oz
OptimizationOptions::new_opt_level_0
·-O0
, or no-O*
argument.OptimizationOptions::new_opt_level_1
·-O1
OptimizationOptions::new_opt_level_2
·-O2
OptimizationOptions::new_opt_level_3
·-O3
OptimizationOptions::new_opt_level_4
·-O4
By default, the run
method will read either binary wasm
or text wat
files,
inspecting the first few bytes for the binary header and choosing as appropriate,
and it will write a binary wasm
file.
This behavior can be changed with OptimizationOptions::reader_file_type
and OptimizationOptions::writer_file_type
.
Enabling and disabling WASM features
The WebAssembly specification has optional features,
represeted by the Feature
enum.
The Feature
variants link to the relevant specifications of each feature when known.
wasm-opt
can be configured with support for them individually using the
OptimizationOptions::enable_feature
and OptimizationOptions::disable_feature
methods.
By default Binaryen (and this crate) enables these common features by default:
The original WebAssembly specification with no additional features is known
as the MVP specification. To enable only the MVP features call
OptimizationOptions::mvp_features_only
.
After resetting to MVP features, additional calls to enable_feature
will
add features to the MVP feature set.
Customizing passes
All Binaryen optimization passes are represented in the Pass
enum, and can be added to OptimizationOptions
via OptimizationOptions::add_pass
.
These are added after the default set of passes, which are
enabled by most OptimizationOptions
constructors. The default passes
can be disabled either with the OptimizationOptions::new_opt_level_0
constructor,
or by calling OptimizationOptions::add_default_passes
with a false
argument.
use wasm_opt::{OptimizationOptions, Pass};
let infile = "hello_world.wasm";
let outfile = "hello_world_optimized.wasm";
// Just run the inliner.
OptimizationOptions::new_opt_level_0()
.add_pass(Pass::InliningOptimizing)
.run(infile, outfile)?;
Note that while this crate exposes all Binaryen passes some may not make sense to actually use — Binaryen is a command-line oriented tool, and some passes are for debug purposes or print directly to the console.
Integrating with existing tooling
For ease of integration with tools that already use wasm-opt
via CLI, this
crate provides the integration
module, which presents an API that is
compatible with std
s Command
. This allows client code to use mostly the
same code path for executing the wasm-opt
CLI, and the crate-based API.
Modules
- Easy integration with tools that already use
wasm-opt
via CLI.
Structs
- Which wasm
Feature
s to enable and disable. - Options related to inlining.
- Optimization options and optimization builder.
- Options that affect how optimization passes behave.
- The set of optimization passes to apply.
- Options for reading the unoptimized wasm module.
- Options for writing the optimized wasm module.
Enums
- Optional wasm features.
- The set of features to apply before applying custom features.
- Module format used by
ReaderOptions
andWriterOptions
. - An error resulting from the
OptimizationOptions::run
method. - The amount of optimization to apply.
- A Binaryen optimization pass.
- The amount of effort to put into reducing module size.